DOC: update the pandas.DataFrame.notna and pandas.Series.notna docstring #20160

datadonK23 · 2018-03-10T14:40:30Z

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Two Validations for pandas.DataFrame.notna and pandas.Series.notna (shared docs).

################################################################################
###################### Docstring (pandas.DataFrame.notna) ######################
################################################################################

Detect existing (non-missing) values.

Return a boolean same-sized object indicating if the values are not NA.
Non-missing values get mapped to True. Characters such as empty
strings `''` or :attr:`numpy.inf` are not considered NA values
(unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).
NA values, such as None or :attr:`numpy.NaN`, get mapped to False
values.

Returns
-------
bool of type DataFrame
    Mask of True/False values for each element in DataFrame that
    indicates whether an element is not an NA value

See Also
--------
DataFrame.notnull : alias of notna
DataFrame.isna : boolean inverse of notna
DataFrame.dropna : omit axes labels with missing values
notna : top-level notna

Examples
--------
Show which entries in a DataFrame are not NA.

>>> df = pd.DataFrame({'age': [5, 6, np.NaN],
...                    'born': [pd.NaT, pd.Timestamp('1939-05-27'),
...                             pd.Timestamp('1940-04-25')],
...                    'name': ['Alfred', 'Batman', ''],
...                    'toy': [None, 'Batmobile', 'Joker']})
>>> df
   age       born    name        toy
0  5.0        NaT  Alfred       None
1  6.0 1939-05-27  Batman  Batmobile
2  NaN 1940-04-25              Joker

>>> df.notna()
     age   born  name    toy
0   True  False  True  False
1   True   True  True   True
2  False   True  True   True

Show which entries in a Series are not NA.

>>> ser = pd.Series([5, 6, np.NaN])
>>> ser
0    5.0
1    6.0
2    NaN
dtype: float64

>>> ser.notna()
0     True
1     True
2    False
dtype: bool

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.notna" correct. :)

################################################################################
####################### Docstring (pandas.Series.notna)  #######################
################################################################################

Detect existing (non-missing) values.

Return a boolean same-sized object indicating if the values are not NA.
Non-missing values get mapped to True. Characters such as empty
strings `''` or :attr:`numpy.inf` are not considered NA values
(unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).
NA values, such as None or :attr:`numpy.NaN`, get mapped to False
values.

Returns
-------
bool of type Series
    Mask of True/False values for each element in Series that
    indicates whether an element is not an NA value

See Also
--------
Series.notnull : alias of notna
Series.isna : boolean inverse of notna
Series.dropna : omit axes labels with missing values
notna : top-level notna

Examples
--------
Show which entries in a DataFrame are not NA.

>>> df = pd.DataFrame({'age': [5, 6, np.NaN],
...                    'born': [pd.NaT, pd.Timestamp('1939-05-27'),
...                             pd.Timestamp('1940-04-25')],
...                    'name': ['Alfred', 'Batman', ''],
...                    'toy': [None, 'Batmobile', 'Joker']})
>>> df
   age       born    name        toy
0  5.0        NaT  Alfred       None
1  6.0 1939-05-27  Batman  Batmobile
2  NaN 1940-04-25              Joker

>>> df.notna()
     age   born  name    toy
0   True  False  True  False
1   True   True  True   True
2  False   True  True   True

Show which entries in a Series are not NA.

>>> ser = pd.Series([5, 6, np.NaN])
>>> ser
0    5.0
1    6.0
2    NaN
dtype: float64

>>> ser.notna()
0     True
1     True
2    False
dtype: bool

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.notna" correct. :)

TomAugspurger · 2018-03-10T14:45:09Z

pandas/core/generic.py

+        values.
+        Everything else get mapped to False values. Characters such as empty
+        strings `''` or :attr:`numpy.inf` are not considered NA values
+        (unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).


Does this attr work? I don't know if its in our API docs. I think it'd be ok to jsut have unless you set ``pandas.options.mode.use_inf_as_na = True``

We have seen :attr: references throughout other docstrings (frame.py). I can change it, thoughts?

It's not the attr itself, but the fact there is nothing to link to I think?

I would rather make this ``pandas.options.mode.use_inf_as_na = True``

TomAugspurger · 2018-03-10T14:46:38Z

pandas/core/generic.py

+        Return a boolean same-sized object indicating if the values are not NA.
+        Non-missing values get mapped to True. Characters such as empty
+        strings `''` or :attr:`numpy.inf` are not considered NA values
+        (unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).


Same here about the pandas option.

villasv · 2018-03-10T14:49:21Z

pandas/core/generic.py

+
+        Returns
+        -------
+        bool of type %(klass)s


Is this type annotation right? It looks like bool is the return variable name (which is not needed).
https://python-sprints.github.io/pandas/guide/pandas_docstring.html#section-3-parameters

Not the name

A complex type then? So it should be somehting like "dict of int", but it looks like it's inverted.

We get a DataFrame or a Series that contains boolean values.
It feels like writing DataFrame of boolor Series of bool may be harder to userstand for new users. Any thoughts?

The guidelines specify that complex types should be written like list of bool. Maybe you can just say that the return type is DataFrame and in the explanation specify that its dtype is bool.

I think the type should be just %(klass)s

%(klass)s Each element of the %(klass)s will be a boolean.

Agreed, it's the closest to the guidelines.

pep8speaks · 2018-03-12T20:33:14Z

Hello @Donk23! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on March 13, 2018 at 13:49 Hours UTC

jorisvandenbossche

Nice docstrings! Added a very minor comment

jorisvandenbossche · 2018-03-12T21:04:43Z

pandas/core/generic.py

+        values.
+        Everything else get mapped to False values. Characters such as empty
+        strings `''` or :attr:`numpy.inf` are not considered NA values
+        (unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).


It's not the attr itself, but the fact there is nothing to link to I think?

I would rather make this ``pandas.options.mode.use_inf_as_na = True``

jorisvandenbossche · 2018-03-12T21:05:06Z

pandas/core/generic.py

        Return a boolean same-sized object indicating if the values are NA.
+        NA values, such as None or :attr:`numpy.NaN`, get mapped to True
+        values.
+        Everything else get mapped to False values. Characters such as empty


get -> gets ?

Sry, not my language. Fixed the typos and changed the link as proposed in .notna docstring.

codecov · 2018-03-13T13:47:24Z

Codecov Report

❗ No coverage uploaded for pull request base (master@e7e0ea8). Click here to learn what that means.
The diff coverage is 100%.

@@            Coverage Diff            @@
##             master   #20160   +/-   ##
=========================================
  Coverage          ?   91.76%           
=========================================
  Files             ?      150           
  Lines             ?    49146           
  Branches          ?        0           
=========================================
  Hits              ?    45097           
  Misses            ?     4049           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`90.14% <100%> (?)`
#single	`41.9% <0%> (?)`

Impacted Files	Coverage Δ
pandas/core/generic.py	`95.85% <100%> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e7e0ea8...744dc61. Read the comment docs.

jorisvandenbossche · 2018-03-13T13:50:47Z

@Donk23 Thanks a lot!

If possible, welcome to check the online docs in a few hours to see if everything is looking OK: http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.DataFrame.notna.html#pandas.DataFrame.notna

datadonK23 added 4 commits March 10, 2018 13:56

DOC: improved docstring of pandas.Index.isna

31b80ae

DOC: improved docstring of pandas.Index.isna

c25704f

DOC: update pandas.DataFrame.isna and pandas.Series.isna

bab0012

DOC: update pandas.DataFrame.notna and pandas.Series.notna

742e566

TomAugspurger reviewed Mar 10, 2018

View reviewed changes

villasv suggested changes Mar 10, 2018

View reviewed changes

datadonK23 and others added 3 commits March 10, 2018 16:01

DOC: Trying to undo accidental commit

04bf6b6

Fixed Returns

cf7bd71

Undo wrong file edit

4a6acea

datadonK23 added 2 commits March 12, 2018 21:34

Undo wrong file edit

939d897

Undo wrong file edit

006ca9b

jorisvandenbossche added the Docs label Mar 12, 2018

jorisvandenbossche reviewed Mar 12, 2018

View reviewed changes

Fixed typos and update link

657539a

datadonK23 mentioned this pull request Mar 13, 2018

DOC: update the pandas.DataFrame.isna and pandas.Series.isna docstring #20138

Merged

5 tasks

Merge branch 'master' into docstring_notna

c630c67

TomAugspurger approved these changes Mar 13, 2018

View reviewed changes

Update generic.py

744dc61

jorisvandenbossche approved these changes Mar 13, 2018

View reviewed changes

jorisvandenbossche merged commit b7b00c5 into pandas-dev:master Mar 13, 2018

datadonK23 deleted the docstring_notna branch March 14, 2018 11:57

Uh oh!

DOC: update the pandas.DataFrame.notna and pandas.Series.notna docstring #20160

DOC: update the pandas.DataFrame.notna and pandas.Series.notna docstring #20160

Uh oh!

Conversation

datadonK23 commented Mar 10, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

villasv Mar 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pep8speaks commented Mar 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comment last updated on March 13, 2018 at 13:49 Hours UTC

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jorisvandenbossche commented Mar 13, 2018

Uh oh!

Uh oh!

villasv Mar 12, 2018 •

edited

Loading

pep8speaks commented Mar 12, 2018 •

edited

Loading

codecov bot commented Mar 13, 2018 •

edited

Loading